home *** CD-ROM | disk | FTP | other *** search
/ Apple WWDC 1996 / WWDC96_1996 (CD).toast / Technology Materials / MacOS 8 Resources / Developer Tools / Mac OS 8 Interfaces & Libraries / Interfaces / AIncludes / FileManager.a < prev    next >
Text File  |  1996-05-01  |  42KB  |  1,131 lines
  1. ;
  2. ;    File:        FileManager.a
  3. ;
  4. ;    Contains:    FileManager Interface
  5. ;
  6. ;    Version:    Technology:    System 8
  7. ;                Release:    Universal Interfaces 3.0d3 on Copland DR1
  8. ;
  9. ;    Copyright:    © 1984-1996 by Apple Computer, Inc.  All rights reserved.
  10. ;
  11. ;    Bugs?:        If you find a problem with this file, send the file and version
  12. ;                information (from above) and the problem description to:
  13. ;
  14. ;                    Internet:    apple.bugs@applelink.apple.com
  15. ;                    AppleLink:    APPLE.BUGS
  16. ;
  17. ;
  18.     IF &TYPE('__FILEMANAGER__') = 'UNDEFINED' THEN
  19. __FILEMANAGER__ SET 1
  20.  
  21.     IF &TYPE('__FILEMANAGERTYPES__') = 'UNDEFINED' THEN
  22.     include 'FileManagerTypes.a'
  23.     ENDIF
  24.     IF &TYPE('__FILES__') = 'UNDEFINED' THEN
  25.     include 'Files.a'
  26.     ENDIF
  27.     IF &TYPE('__FINDER__') = 'UNDEFINED' THEN
  28.     include 'Finder.a'
  29.     ENDIF
  30. ;  You can use FileManager.h or FileManagerSPI.h, but not both 
  31.     IF &TYPE('_FILEMANAGERSPI__') = 'UNDEFINED' THEN
  32.     IF FOR_SYSTEM8_PREEMPTIVE THEN
  33. ; >>>>>>>>>>>>>>>>>>>>>>>>>>>>> F o u n d a t i o n  D e f i n i t i o n s <<<<<<<<<<<<<<<<<<<<<<<<<<<<<
  34. ;
  35. ;****************************************************************************
  36. ;    CONSTANTS & TYPES
  37. ;****************************************************************************
  38. ;
  39.  
  40. kFSInfoInvalidVersion            EQU        0
  41. kFSInfoD10Version                EQU        1
  42. kFSInfoD11Version                EQU        2
  43. kFSInfoCurrentReleasedVersion    EQU        2
  44. ; typedef UInt32                         FSInfoVersion
  45.  
  46.  
  47. kFSHFSPath                        EQU        1
  48. kFSUnixPath                        EQU        2
  49. kFSDOSPath                        EQU        3
  50. ; typedef UInt32                         FSPathnameType
  51.  
  52.  
  53. kFSFileIsLocked                    EQU        $00000001
  54. ; typedef OptionBits                     FSFileFlags
  55.  
  56. FSFileInformation        RECORD 0
  57. flags                     ds.l    1                ; offset: $0 (0)
  58. finderInfo                 ds        FInfo            ; offset: $4 (4)
  59. extendedFinderInfo         ds        FXInfo            ; offset: $14 (20)
  60. creationDate             ds        FSDate            ; offset: $24 (36)
  61. modificationDate         ds        FSDate            ; offset: $34 (52)
  62. dataForkSize             ds        FSSize            ; offset: $44 (68)
  63. resourceForkSize         ds        FSSize            ; offset: $4C (76)
  64. sizeof                     EQU *                    ; size:   $54 (84)
  65.                         ENDR
  66. ; typedef struct FSFileInformation *    FSFileInformationPtr
  67.  
  68.  
  69. kFSFolderIsLocked                EQU        $00000001
  70. ; typedef OptionBits                     FSFolderFlags
  71.  
  72. FSFolderInformation        RECORD 0
  73. flags                     ds.l    1                ; offset: $0 (0)
  74. finderInfo                 ds        DInfo            ; offset: $4 (4)
  75. extendedFinderInfo         ds        DXInfo            ; offset: $14 (20)
  76. creationDate             ds        FSDate            ; offset: $24 (36)
  77. modificationDate         ds        FSDate            ; offset: $34 (52)
  78. sizeof                     EQU *                    ; size:   $44 (68)
  79.                         ENDR
  80. ; typedef struct FSFolderInformation *    FSFolderInformationPtr
  81.  
  82.  
  83. kFSVolumeIsLockedInHardware        EQU        $00000001
  84. kFSVolumeIsLockedInSoftware        EQU        $00000002
  85. kFSVolumeIsLockedMask            EQU        $00000003
  86. kFSVolumeIsEjectable            EQU        $00000004
  87. kFSVolumeIsOffline                EQU        $00000008
  88. kFSVolumeIsRemote                EQU        $00000010
  89. ; typedef OptionBits                     FSVolumeFlags
  90.  
  91. FSVolumeInformation        RECORD 0
  92. folderInfo                 ds        FSFolderInformation ; offset: $0 (0)
  93. flags                     ds.l    1                ; offset: $44 (68)
  94. totalBytes                 ds        FSSize            ; offset: $48 (72)
  95. freeBytes                 ds        FSSize            ; offset: $50 (80)
  96. constraints                 ds        FSMountAccessConstraints ; offset: $58 (88)
  97. capabilities             ds.l    1                ; offset: $64 (100)
  98. sizeof                     EQU *                    ; size:   $68 (104)
  99.                         ENDR
  100. ; typedef struct FSVolumeInformation *    FSVolumeInformationPtr
  101.  
  102. FSObjectInformation        RECORD 0
  103. objectType                 ds.l    1                ; offset: $0 (0)
  104. fileInfo                 ds        FSFileInformation ; offset: $4 (4)
  105.                          ORG 4
  106. folderInfo                 ds        FSFolderInformation ; offset: $4 (4)
  107.                          ORG 4
  108. volumeInfo                 ds        FSVolumeInformation ; offset: $4 (4)
  109. sizeof                     EQU *                    ; size:   $6C (108)
  110.                         ENDR
  111. ; typedef struct FSObjectInformation *    FSObjectInformationPtr
  112.  
  113. ; >>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>> C O N T A I N E R S <<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<
  114. ;
  115. ;****************************************************************************
  116. ;    OBJECTS
  117. ;****************************************************************************
  118. ;
  119. ;
  120. ;    Function:    FSObjectRefClone
  121. ;    Purpose:    Return a copy of an FSObjectRef such that the copy also needs to be disposed.
  122. ;    Inputs:
  123. ;                object_t        The object ref to be cloned.
  124. ;    Outputs:
  125. ;                clone_o            Copy of object_t.
  126. ;    Notes:
  127. ;                The value returned is the same value passed as input in object_t.  This call
  128. ;                would typically be used to balance a future call to FSObjectRefDispose.  Some
  129. ;                examples where it might be used:
  130. ;                    * A called procedure needs to save an FSObjectRef for future use, but the
  131. ;                      calling conventions dictate that the caller is responsible for disposing
  132. ;                      of the ref.  The called function could call FSObjectRefClone to make its
  133. ;                      copy.  The caller can safely dispose of the ref, yet the callee can use
  134. ;                      the ref until doing its own dispose.
  135. ;                    * In object-oriented programming, an object could be passed an FSObjectRef
  136. ;                      in its constructor.  The destructor would be expected to dispose the ref,
  137. ;                      but so would the routine that created the object.  FSObjectRefClone could
  138. ;                      be used in the constructor.
  139. ;                
  140. ;                The returned FSObjectRef is registered to the calling process (as must object_t).
  141. ;
  142. ;
  143. ; extern OSStatus FSObjectRefClone(FSObjectRef object_t, FSObjectRef *clone_o)
  144. ;
  145.     IF GENERATINGCFM THEN
  146.         IMPORT_CFM_FUNCTION FSObjectRefClone
  147.     ENDIF
  148.  
  149. ;
  150. ;    Function:    FSObjectRefDispose
  151. ;    Purpose:    Dispose of an FSObjectRef previously returned to a process.
  152. ;    Inputs:
  153. ;                object_t        The object ref to be disposed.
  154. ;    Outputs:
  155. ;    Notes:
  156. ;                A process must dispose of all FSObjectRefs returned to it.  The FSObjectRefs
  157. ;                may be returned as explicit output parameters, or as properties.  If a ref
  158. ;                is returned several times for a given object, it must be disposed for each
  159. ;                time it was returned.
  160. ;                
  161. ;                When all refs to a given object are disposed, the File Manager will dispose
  162. ;                of any resources it allocated in order to operate on that object.  All refs
  163. ;                for a process will be automatically disposed upon process termination.
  164. ;                
  165. ;                For refs returned as properties (especially when iterating over muliple
  166. ;                objects), the FSObjectRefDisposeBulk call may be more convenient.
  167. ;
  168. ;
  169. ; extern OSStatus FSObjectRefDispose(FSObjectRef object_t)
  170. ;
  171.     IF GENERATINGCFM THEN
  172.         IMPORT_CFM_FUNCTION FSObjectRefDispose
  173.     ENDIF
  174.  
  175. ;
  176. ;    Function:    FSObjectFlush
  177. ;    Purpose:    Flushes any data cached by the File Manager for the given object.
  178. ;    Inputs:
  179. ;                object_t        The object to be flushed.
  180. ;    Outputs:
  181. ;    Notes:
  182. ;                If object_t is a file, then any data written to that file (via a stream or backing store,
  183. ;                regardless of the process that opened the stream or backing store) will be written by the
  184. ;                File Manager to any underlying device.  If object_t is a volume, then any data written to
  185. ;                any file on that volume will be flushed.
  186. ;                
  187. ;                Any change to properties of object_t will be flushed (regardless of the object's type).
  188. ;                
  189. ;                Data about the object (or contained in the object) may still reside in the File Manager's
  190. ;                caches, but any changes will have been written out by the File Manager.  Note that the
  191. ;                underlying device's driver, or the device itself, may cache some data, so the File Manager
  192. ;                cannot guarantee that all data has actually been written to the underlying media.
  193. ;
  194. ;
  195. ;
  196. ;
  197. ;
  198. ; extern OSStatus FSObjectFlush(FSObjectRef object_t)
  199. ;
  200.     IF GENERATINGCFM THEN
  201.         IMPORT_CFM_FUNCTION FSObjectFlush
  202.     ENDIF
  203.  
  204. ;
  205. ;    Function:    FSObjectRefRegister
  206. ;    Purpose:    Allow an FSObjectRef to be used by another process.
  207. ;    Inputs:
  208. ;                senderObject_t        The object ref.
  209. ;                receiverPid_i        The other process that will be using senderObject_t.
  210. ;    Outputs:
  211. ;    Notes:
  212. ;                This call allows one process to send an FSObjectRef to another process
  213. ;                such that the other process can use the FSObjectRef itself.  The process
  214. ;                specified by receiverPid_i must also dispose of senderObject_t.  The File
  215. ;                Manager acts as if senderObject_t has been returned to receiverPid_i.
  216. ;
  217. ;
  218. ;
  219. ;
  220. ;
  221. ;                You might use this call if you have several processes where one process
  222. ;                (typically a server of some kind) obtains FSObjectRefs for use by other
  223. ;                processes (typically clients of that server).  If the other process (as
  224. ;                specified by receiverPid_i) won't actually call the File Manager with
  225. ;                that FSObjectRef, then it doesn't need to be registered to that process.
  226. ;
  227. ;                It would also be possible to have the server process make all of the
  228. ;                calls to the File Manager.  FSObjectRefs could still be passed between
  229. ;                client and server, but if the clients never use the refs directly, then
  230. ;                there would be no need to register the refs to those clients.  (But beware:
  231. ;                the server would still be responsible for disposing of all refs returned to
  232. ;                it; the server would probably have some cleanup and disposal to do if one
  233. ;                of its client processes were to terminate.)
  234. ;
  235. ;
  236. ; extern OSStatus FSObjectRefRegister(FSObjectRef senderObject_t, KernelProcessID receiverPid_i)
  237. ;
  238.     IF GENERATINGCFM THEN
  239.         IMPORT_CFM_FUNCTION FSObjectRefRegister
  240.     ENDIF
  241.  
  242. ;
  243. ;============================================================================
  244. ;    Volume Sets
  245. ;============================================================================
  246. ;
  247. ;
  248. ;    Function:    FSVolumeSetGetInformation
  249. ;    Purpose:    Returns an FSObjectRef for a Volume Set specified by an
  250. ;                FSVolumeSetObjID.
  251. ;    Inputs:
  252. ;                volumeSet_t                The volume set.
  253. ;    Outputs:
  254. ;                object_o                Object ref for the volume set.
  255. ;                includesBootVolume_o    True if the volume set includes the boot volume.
  256. ;    Notes:
  257. ;                There is currently only one volume set.  In the future there could be others
  258. ;                (perhaps file servers; perhaps to support multiple local users).
  259. ;
  260. ;
  261. ; extern OSStatus FSVolumeSetGetInformation(FSVolumeSetObjID volumeSet_t, Boolean *includesBootVolume_o, FSObjectRef *object_o)
  262. ;
  263.     IF GENERATINGCFM THEN
  264.         IMPORT_CFM_FUNCTION FSVolumeSetGetInformation
  265.     ENDIF
  266.  
  267. ;
  268. ;============================================================================
  269. ;    Folders
  270. ;============================================================================
  271. ;
  272. ;
  273. ;    Function:    FSFolderCreate
  274. ;    Purpose:    Create a new named folder within a specified folder
  275. ;    Inputs:
  276. ;                containerRef_t        The object ref of the parent of the new folder.
  277. ;                folderName_i        The name of the new folder as a _persistent_ TextObject.
  278. ;    Outputs:
  279. ;                folderRef_o            The object ref of the new folder.
  280. ;    Notes:
  281. ;                An error will be returned if the folder already exists.
  282. ;
  283. ;
  284. ; extern OSStatus FSFolderCreate(FSObjectRef containerRef_t, ConstFSName folderName_i, FSObjectRef *folderRef_o)
  285. ;
  286.     IF GENERATINGCFM THEN
  287.         IMPORT_CFM_FUNCTION FSFolderCreate
  288.     ENDIF
  289.  
  290. ;
  291. ;============================================================================
  292. ;    Files
  293. ;============================================================================
  294. ;
  295. ;
  296. ;    Function:    FSFileCreate
  297. ;    Purpose:    Create a new named file within a specified folder
  298. ;    Inputs:
  299. ;                containerRef_t        The object ref of the parent of the new file.
  300. ;                fileName_i            The name of the new file as a _persistent_ TextObject.
  301. ;                fileCreator_i        The new file's Finder creator.
  302. ;                fileType_i            The new file's Finder type.                
  303. ;    Outputs:
  304. ;                fileRef_o            The object ref of the new file.
  305. ;    Notes:
  306. ;                An error will be returned if the file already exists.
  307. ;
  308. ;
  309. ; extern OSStatus FSFileCreate(FSObjectRef containerRef_t, ConstFSName fileName_i, OSType fileCreator_i, OSType fileType_i, FSObjectRef *fileRef_o)
  310. ;
  311.     IF GENERATINGCFM THEN
  312.         IMPORT_CFM_FUNCTION FSFileCreate
  313.     ENDIF
  314.  
  315. ;
  316. ;============================================================================
  317. ;    Folder and File Requests
  318. ;============================================================================
  319. ;
  320. ;
  321. ;    Function:    FSObjectDelete
  322. ;    Purpose:    Deletes an object.  The FSObjectRef is NOT disposed; you must still dispose it yourself.
  323. ;                Further attempts to use the ref will return errors (such as E_ObjectNotFound).
  324. ;
  325. ;    Inputs:
  326. ;                object_t        The object to be deleted.
  327. ;    Outputs:
  328. ;
  329. ;
  330. ; extern OSStatus FSObjectDelete(FSObjectRef object_t)
  331. ;
  332.     IF GENERATINGCFM THEN
  333.         IMPORT_CFM_FUNCTION FSObjectDelete
  334.     ENDIF
  335.  
  336. ;
  337. ;    Function:    FSObjectMoveRename
  338. ;    Purpose:    Move a file or folder to a new folder and (optionally) rename it.
  339. ;    Inputs:
  340. ;                sourceObjectRef_t    The object ref of the file or folder to move.
  341. ;                destContainerRef_i    The object ref of the new parent folder.
  342. ;                newObjectName_i        The new name for the moved file or folder (optional).
  343. ;    Outputs:
  344. ;    Notes:
  345. ;                An error will be returned if another file or folder exists in the
  346. ;                folder specified by destContainerRef_i which has the same name as
  347. ;                sourceObjectRef_t.
  348. ;
  349. ;
  350. ; extern OSStatus FSObjectMoveRename(FSObjectRef sourceObjectRef_t, FSObjectRef destContainerRef_i, ConstFSName newObjectName_i)
  351. ;
  352.     IF GENERATINGCFM THEN
  353.         IMPORT_CFM_FUNCTION FSObjectMoveRename
  354.     ENDIF
  355.  
  356. ;
  357. ;    Function:    FSObjectRename
  358. ;    Purpose:    Rename a file or folder.
  359. ;    Inputs:
  360. ;                sourceObjectRef_t    The object ref of the file or folder to rename.
  361. ;                newObjectName_i        The new name for the file or folder.
  362. ;    Outputs:
  363. ;    Notes:
  364. ;                An error will be returned if another file or folder exists in the
  365. ;                same folder as sourceObjectRef_t with the name newObjectName_i.
  366. ;
  367. ;
  368. ; extern OSStatus FSObjectRename(FSObjectRef sourceObjectRef_t, ConstFSName newObjectName_i)
  369. ;
  370.     IF GENERATINGCFM THEN
  371.         IMPORT_CFM_FUNCTION FSObjectRename
  372.     ENDIF
  373.  
  374. ; >>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>> C a p a b i l i t i e s <<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<
  375. ;
  376. ;****************************************************************************
  377. ;    PROPERTY ACCESS METHODS
  378. ;****************************************************************************
  379. ;
  380. ;
  381. ;++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
  382. ;    Object Property Simple Values
  383. ;++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
  384. ;
  385. ;
  386. ;    Function:    FSObjectGetOneProperty
  387. ;    Purpose:    Get one property attribute of an object.
  388. ;    Inputs:
  389. ;                objectRef_t            The object ref.
  390. ;                property_i            The property attribute to get.
  391. ;                propertySize_i        The size of the property buffer specified
  392. ;                                    by propertyValue_o
  393. ;    Outputs:
  394. ;                property_o            The requested property data.
  395. ;    Notes:
  396. ;                This function can be used to get the value of a simple property as
  397. ;                well as other attributes of all properties such as size, type,
  398. ;                state, etc. The attribute to get is specified by
  399. ;                property_i->attribute.
  400. ;                
  401. ;                Fork property values must be obtained by using the stream or mapped
  402. ;                file access routines.
  403. ;
  404. ;
  405. ; extern OSStatus FSObjectGetOneProperty(FSObjectRef objectRef_t, const FSProperty *property_i, ByteCount propertySize_i, LogicalAddress property_o)
  406. ;
  407.     IF GENERATINGCFM THEN
  408.         IMPORT_CFM_FUNCTION FSObjectGetOneProperty
  409.     ENDIF
  410.  
  411. ;
  412. ;    Function:    FSObjectGetInformation
  413. ;    Purpose:    Get a predefined aggregate property set for an object.
  414. ;    Inputs:
  415. ;                objectRef_t            The object ref.
  416. ;                infoVersion_i        The version of the FSObjectInformation data record
  417. ;                                    specified by objectInfo_o.
  418. ;    Outputs:
  419. ;                objectInfo_o        The aggregate property data (optional).
  420. ;                objectName_o        The name of the specified object (optional).
  421. ;    Notes:
  422. ;                Use kFSInfoCurrentReleasedVersion for infoVersion_i to specify the latest
  423. ;                version of the FSObjectInformation record. infoVersion_i is ignored
  424. ;                if objectInfo_o is omitted.
  425. ;                
  426. ;                objectName_o, if specified, must reference a preinitialized persistent
  427. ;                TextObject of sufficient size to contain the object's name.
  428. ;
  429. ;
  430. ; extern OSStatus FSObjectGetInformation(FSObjectRef objectRef_t, FSInfoVersion infoVersion_i, FSObjectInformation *objectInfo_o, FSName objectName_o)
  431. ;
  432.     IF GENERATINGCFM THEN
  433.         IMPORT_CFM_FUNCTION FSObjectGetInformation
  434.     ENDIF
  435.  
  436. ;
  437. ;    Function:    FSObjectGetVolumeInformation
  438. ;    Purpose:    Get a predefined aggregate property set for a volume object.
  439. ;    Inputs:
  440. ;                volumeItemRef_t        The object ref of a file or folder on the volume or
  441. ;                                    the volume itself.
  442. ;                infoVersion_i        The version of the FSObjectInformation data record
  443. ;                                    specified by volumeInfo_o.
  444. ;    Outputs:
  445. ;                volumeInfo_o        The aggregate volume property data (optional).
  446. ;                volumeObjectRef_o    The object ref of the volume (optional).
  447. ;                volumeName_o        The name of the volume (optional).
  448. ;    Notes:
  449. ;                Use kFSInfoCurrentReleasedVersion for infoVersion_i to specify the latest
  450. ;                version of the FSObjectInformation record. infoVersion_i is ignored
  451. ;                if volumeInfo_o is omitted.
  452. ;                
  453. ;                volumeName_o, if specified, must reference a preinitialized persistent
  454. ;                TextObject of sufficient size to contain the volume's name.
  455. ;                
  456. ;                This function is functionally equivalent to FSObjectGetInformation when
  457. ;                the target object ref is the volume's object ref.
  458. ;
  459. ;
  460. ; extern OSStatus FSObjectGetVolumeInformation(FSObjectRef volumeItemRef_t, FSInfoVersion infoVersion_i, FSObjectInformation *volumeInfo_o, FSObjectRef *volumeObjectRef_o, FSName volumeName_o)
  461. ;
  462.     IF GENERATINGCFM THEN
  463.         IMPORT_CFM_FUNCTION FSObjectGetVolumeInformation
  464.     ENDIF
  465.  
  466. ;
  467. ;    Function:    FSObjectSetOneProperty
  468. ;    Purpose:    Set one property attribute of an object.
  469. ;    Inputs:
  470. ;                objectRef_t            The object ref.
  471. ;                property_i            The property attribute to set.
  472. ;                propertySize_i        The size of the property buffer specified
  473. ;                                    by propertyValue_i.
  474. ;                propertyData_i        The new property data.
  475. ;    Outputs:
  476. ;    Notes:
  477. ;                Fork property values must be changed by using the stream or mapped
  478. ;                file access routines.
  479. ;
  480. ;
  481. ; extern OSStatus FSObjectSetOneProperty(FSObjectRef objectRef_t, const FSProperty *property_i, ByteCount propertySize_i, ConstLogicalAddress propertyData_i)
  482. ;
  483.     IF GENERATINGCFM THEN
  484.         IMPORT_CFM_FUNCTION FSObjectSetOneProperty
  485.     ENDIF
  486.  
  487. ;
  488. ;============================================================================
  489. ;    Stream-based Access Method
  490. ;============================================================================
  491. ;
  492. ;
  493. ;    Function:    FSStreamClose
  494. ;    Purpose:    Close a stream previously opened with FSStreamOpen or FSStreamOpenWithConstraints.
  495. ;    Inputs:
  496. ;                stream_t            The stream to close.
  497. ;    Outputs:
  498. ;    Notes:
  499. ;                Any data written to the stream is flushed (written by the File Manager) before the
  500. ;                stream is closed.  The FSStreamObjID, stream_t, may no longer be used.  Any resources
  501. ;                allocated by the File Manager for use by this stream will be disposed.
  502. ;
  503. ;
  504. ; extern OSStatus FSStreamClose(FSStreamObjID stream_t)
  505. ;
  506.     IF GENERATINGCFM THEN
  507.         IMPORT_CFM_FUNCTION FSStreamClose
  508.     ENDIF
  509.  
  510. ;
  511. ;    Function:    FSStreamFlush
  512. ;    Purpose:    Any data written to the stream will be written by the File Manager.
  513. ;    Inputs:
  514. ;                stream_t            The stream to flush.
  515. ;    Outputs:
  516. ;    Notes:
  517. ;                Stream data may still reside in the File Manager's caches, but any changes will have
  518. ;                been written out by the File Manager.  Note that the underlying device's driver, or
  519. ;                the device itself, may cache some data, so the File Manager cannot guarantee that
  520. ;                all data has actually been written to the underlying media.
  521. ;                
  522. ;                Other information about the object (such as its modification date) might not be flushed
  523. ;                by this call, though any volume-level data needed to access the stream will be.
  524. ;
  525. ;
  526. ;
  527. ;
  528. ; extern OSStatus FSStreamFlush(FSStreamObjID stream_t)
  529. ;
  530.     IF GENERATINGCFM THEN
  531.         IMPORT_CFM_FUNCTION FSStreamFlush
  532.     ENDIF
  533.  
  534. ;
  535. ;    Function:    FSStreamGetAbsoluteEOF
  536. ;    Purpose:    Get the logical end-of-file of an open file fork.
  537. ;    Inputs:
  538. ;                stream_t            The target stream.
  539. ;    Outputs:
  540. ;                currentEOF_o        The logical end-of-file of the specified
  541. ;                                    stream.
  542. ;    Notes:
  543. ;
  544. ;
  545. ; extern OSStatus FSStreamGetAbsoluteEOF(FSStreamObjID stream_t, FSOffset *currentEOF_o)
  546. ;
  547.     IF GENERATINGCFM THEN
  548.         IMPORT_CFM_FUNCTION FSStreamGetAbsoluteEOF
  549.     ENDIF
  550.  
  551. ;
  552. ;    Function:    FSStreamGetMark
  553. ;    Purpose:    Returns the current mark (position offset) for a stream.
  554. ;    Inputs:
  555. ;                stream_t            The stream.
  556. ;    Outputs:
  557. ;                currentMark_o        Current offset in the stream, stream_t.
  558. ;    Notes:
  559. ;                This call returns the offset from the start of the file that would be
  560. ;                equivalent to using a FSForkPositionDescriptor whose positionOffset is
  561. ;                0, and whose positionMode is kFSFromMark.  A stream's mark is set to
  562. ;                the byte following the last read or write, or via FSStreamSetMark.
  563. ;
  564. ;
  565. ; extern OSStatus FSStreamGetMark(FSStreamObjID stream_t, FSOffset *currentMark_o)
  566. ;
  567.     IF GENERATINGCFM THEN
  568.         IMPORT_CFM_FUNCTION FSStreamGetMark
  569.     ENDIF
  570.  
  571. ;
  572. ;    Function:    FSStreamOpen
  573. ;    Purpose:    Open a file fork for stream access.
  574. ;    Inputs:
  575. ;                fileObjectRef_t        The object ref of the file to open.
  576. ;                fork_i                The fork to open.
  577. ;    Outputs:
  578. ;                stream_o            The new stream ID.
  579. ;    Notes:
  580. ;                The only allowable values for fork_i are kFSDataFork and
  581. ;                kFSResourceFork.
  582. ;                
  583. ;                FSStreamOpen attempts to open the fork with exclusive read/write
  584. ;                access. If the file is locked or is open on another stream with
  585. ;                conflicting access constraints, then an error is returned. Use
  586. ;                FSStreamOpenWithConstraints() to specify particular access
  587. ;                constratins.
  588. ;
  589. ;
  590. ; extern OSStatus FSStreamOpen(FSObjectRef fileObjectRef_i, FSForkType fork_i, FSStreamObjID *stream_o)
  591. ;
  592.     IF GENERATINGCFM THEN
  593.         IMPORT_CFM_FUNCTION FSStreamOpen
  594.     ENDIF
  595.  
  596. ;
  597. ;    Function:    FSStreamSetAbsoluteEOF
  598. ;    Purpose:    Set the logical end-of-file of an open file fork.
  599. ;    Inputs:
  600. ;                stream_t            The target stream.
  601. ;                eof_i                The new logical end-of-file of the stream.
  602. ;    Outputs:
  603. ;    Notes:
  604. ;                If there is not enough space on the volume to set the EOF of
  605. ;                the fork specified by stream_t to eof_i, then the EOF is not
  606. ;                changed and an error is returned.
  607. ;
  608. ;
  609. ; extern OSStatus FSStreamSetAbsoluteEOF(FSStreamObjID stream_t, const FSOffset *eof_i)
  610. ;
  611.     IF GENERATINGCFM THEN
  612.         IMPORT_CFM_FUNCTION FSStreamSetAbsoluteEOF
  613.     ENDIF
  614.  
  615. ;
  616. ;    Function:    FSStreamSetMark
  617. ;    Purpose:    Sets the current mark (position offset) for a stream.
  618. ;    Inputs:
  619. ;                stream_t            The stream.
  620. ;                newPosition_i        The new position of the stream's mark.
  621. ;                options_i
  622. ;    Outputs:
  623. ;                originalMark_o        The stream's mark, before being changed (relative
  624. ;                                    to the start of the stream).
  625. ;                currentMark_o        The new mark, relative to the start of the stream.
  626. ;    Notes:
  627. ;                A stream's mark is usually used for sequential access to a stream,
  628. ;                or to position relative to the ending position of the last operation
  629. ;                on a stream.  This call lets you explicitly set the mark for future
  630. ;                operations that will operate relative to the current mark.
  631. ;                
  632. ;                If kFSMarkPinToEOF is set in options_i, and the new position specified
  633. ;                by newPosition_i would exceed the current end of the stream (also known
  634. ;                as End Of File or EOF), then the mark will be set to the EOF and E_NoError
  635. ;                is returned.  Otherwise, an error will returned.  The mark may never be
  636. ;                set past the end of the stream.
  637. ;
  638. ;
  639. ;
  640. ;
  641. ; extern OSStatus FSStreamSetMark(FSStreamObjID stream_t, const FSForkPositionDescriptor *newPosition_i, FSStreamSetMarkOptions options_i, FSOffset *originalMark_o, FSOffset *currentMark_o)
  642. ;
  643.     IF GENERATINGCFM THEN
  644.         IMPORT_CFM_FUNCTION FSStreamSetMark
  645.     ENDIF
  646.  
  647. ;
  648. ;    Function:    FSStreamSimpleRead
  649. ;    Purpose:    Read data from an open stream.
  650. ;    Inputs:
  651. ;                stream_t            The target stream.
  652. ;                requestLength_i        The number of bytes to read from the fork.
  653. ;                position_i            The starting position for the read operation
  654. ;                
  655. ;    Outputs:
  656. ;                data_o                The address of a buffer to the read bytes.
  657. ;                actualLength_o        The actual number of bytes read from the file (optional).
  658. ;                currentMark_o        The mark position within the stream after the
  659. ;                                    read operation (optional)
  660. ;    Notes:            
  661. ;                The stream mark is always positioned after the last byte read after all
  662. ;                calls to FSStreamSimpleRead().
  663. ;
  664. ;                If an attempt is made to read beyond the logical EOF of the fork, then
  665. ;                the mark is set at the logical EOF of the file, actualLength_o contains
  666. ;                the actual number of bytes read, and an error is returned.
  667. ;
  668. ;
  669. ; extern OSStatus FSStreamSimpleRead(FSStreamObjID stream_t, ByteCount requestLength_i, const FSForkPositionDescriptor *position_i, LogicalAddress data_o, ByteCount *actualLength_o, FSOffset *currentMark_o)
  670. ;
  671.     IF GENERATINGCFM THEN
  672.         IMPORT_CFM_FUNCTION FSStreamSimpleRead
  673.     ENDIF
  674.  
  675. ;
  676. ;    Function:    FSStreamSimpleWrite
  677. ;    Purpose:    Write data to an open stream.
  678. ;    Inputs:
  679. ;                stream_t            The target stream.
  680. ;                requestLength_i        The number of bytes to write to the fork.
  681. ;                data_i                The address of a buffer contating the data to write.
  682. ;                position_i            The starting position for the write operation
  683. ;                
  684. ;    Outputs:
  685. ;                actualLength_o        The actual number of bytes written to the file (optional).
  686. ;                currentMark_o        The mark position within the stream after the
  687. ;                                    read operation (optional)
  688. ;    Notes:            
  689. ;                The stream mark is always positioned after the last byte written after all
  690. ;                calls to FSStreamSimpleWrite().
  691. ;
  692. ;                If an attempt is made to write beyond the logical EOF of the fork, then
  693. ;                the EOF is moved to the byte following the last written byte.
  694. ;
  695. ;
  696. ; extern OSStatus FSStreamSimpleWrite(FSStreamObjID stream_t, ByteCount requestLength_i, ConstLogicalAddress data_i, const FSForkPositionDescriptor *position_i, ByteCount *actualLength_o, FSOffset *currentMark_o)
  697. ;
  698.     IF GENERATINGCFM THEN
  699.         IMPORT_CFM_FUNCTION FSStreamSimpleWrite
  700.     ENDIF
  701.  
  702. ;
  703. ;============================================================================
  704. ;    Memory-mapped Access Method(Backing Store Requests)
  705. ;============================================================================
  706. ;
  707. ;
  708. ;    Function:    FSMappedFileClose
  709. ;    Purpose:    Closes an access path to a file used for backing store.
  710. ;    Inputs:
  711. ;                backingStore_t        The backing store object.
  712. ;    Outputs:
  713. ;    Notes:
  714. ;                Basically the same as FSStreamClose, but for a backing store.
  715. ;                
  716. ;                All data written to this backing store (by writing to pages backed by
  717. ;                this store) will be flushed (written) by the File Manager.
  718. ;
  719. ;
  720. ; extern OSStatus FSMappedFileClose(FSBackingStoreObjID backingStore_t)
  721. ;
  722.     IF GENERATINGCFM THEN
  723.         IMPORT_CFM_FUNCTION FSMappedFileClose
  724.     ENDIF
  725.  
  726. ;
  727. ;    Function:    FSMappedFileFlush
  728. ;    Purpose:    Any data written via the backing store will be written by the File Manager.
  729. ;    Inputs:
  730. ;                backingStore_t        The backing store to flush.
  731. ;    Outputs:
  732. ;    Notes:
  733. ;                Data may still reside in the File Manager's caches, but any changes will have been
  734. ;                written out by the File Manager.  Note that the underlying device's driver, or the
  735. ;                device itself, may cache some data, so the File Manager cannot guarantee that all
  736. ;                data has actually been written to the underlying media.
  737. ;                
  738. ;                Other information about the object (such as its modification date) might not be flushed
  739. ;                by this call, though any volume-level data needed to access the fork data will be.
  740. ;
  741. ;
  742. ; extern OSStatus FSMappedFileFlush(FSBackingStoreObjID backingStore_t)
  743. ;
  744.     IF GENERATINGCFM THEN
  745.         IMPORT_CFM_FUNCTION FSMappedFileFlush
  746.     ENDIF
  747.  
  748. ;
  749. ;    Function:    FSMappedFileGetAbsoluteEOF
  750. ;    Purpose:    Return the EOF (length) of the fork being accessed by the given backing store.
  751. ;    Inputs:
  752. ;                backingStore_t        The backing store used to access the fork.
  753. ;    Outputs:
  754. ;                currentEOF_o        The size, in bytes, of the fork.
  755. ;    Notes:
  756. ;                Since access to a fork via a backing store (i.e. memory mapped file access) is
  757. ;                accomplished by directly accessing memory pages, the virtual memory system must
  758. ;                read and write entire pages.  If the last page is modified, the entire page is
  759. ;                written, resulting in the fork size being rounded up to a multiple of a page size.
  760. ;                Similarly for access to pages beyond the fork's EOF.
  761. ;                
  762. ;                This call returns the current EOF (length) of the underlying fork.  This may be
  763. ;                set implicitly by writing to backed pages, or by using the FSMappedFileSetEOF
  764. ;                call.  It may also be changed by streams opened to the same fork.
  765. ;
  766. ;
  767. ; extern OSStatus FSMappedFileGetAbsoluteEOF(FSBackingStoreObjID backingStore_t, FSOffset *currentEOF_0)
  768. ;
  769.     IF GENERATINGCFM THEN
  770.         IMPORT_CFM_FUNCTION FSMappedFileGetAbsoluteEOF
  771.     ENDIF
  772.  
  773. ;
  774. ;    Function:    FSMappedFileOpen
  775. ;    Purpose:    Open a file fork for memory mapped access.
  776. ;    Inputs:
  777. ;                fileObjectRef_t        The object ref of the file to open.
  778. ;                fork_i                The fork to open.
  779. ;    Outputs:
  780. ;                backingStore_o        The backing store used to access the fork.
  781. ;    Notes:
  782. ;                The only allowable values for fork_i are kFSDataFork and
  783. ;                kFSResourceFork.
  784. ;                
  785. ;                FSMappedFileOpen attempts to open the fork with exclusive read/write
  786. ;                access. If the file is locked or is open on another stream with
  787. ;                conflicting access constraints, then an error is returned. Use
  788. ;                FSMappedFileOpenWithConstraints() to specify particular access
  789. ;                constratins.
  790. ;
  791. ;
  792. ; extern OSStatus FSMappedFileOpen(FSObjectRef fileObjectRef_t, FSForkType fork_i, FSBackingStoreObjID *backingStore_o)
  793. ;
  794.     IF GENERATINGCFM THEN
  795.         IMPORT_CFM_FUNCTION FSMappedFileOpen
  796.     ENDIF
  797.  
  798. ;
  799. ;    Function:    FSMappedFileSetAbsoluteEOF
  800. ;    Purpose:    Sets the EOF (length) of the fork being accessed by the given backing store.
  801. ;    Inputs:
  802. ;                backingStore_t        The backing store used to access the fork.
  803. ;                eof_i                The new length (EOF) of the fork.
  804. ;    Outputs:
  805. ;                currentEOF_o        The new size, in bytes, of the fork.
  806. ;    Notes:
  807. ;                Since access to a fork via a backing store (i.e. memory mapped file access) is
  808. ;                accomplished by directly accessing memory pages, the virtual memory system must
  809. ;                read and write entire pages.  If the last page is modified, the entire page is
  810. ;                written, resulting in the fork size being rounded up to a multiple of a page size.
  811. ;                Similarly for access to pages beyond the fork's EOF.
  812. ;                
  813. ;                This call allows the EOF to be explicitly set for a fork being accessed via a
  814. ;                backing store.  Any data beyond the EOF will not actually be written to the fork.
  815. ;                The File Manager has no way to detect whether access to pages occurs beyond the
  816. ;                EOF; it is a programming error to access bytes beyond the EOF via a backing store.
  817. ;                
  818. ;                This call would typically be used when a fork has been memory mapped to enable
  819. ;                convenient access to a file's data structures as if it were completely in memory.
  820. ;                You would make all changes to the data structures, then use this call to indicate
  821. ;                the number of bytes that are valid and should be written to the fork.
  822. ;
  823. ;
  824. ; extern OSStatus FSMappedFileSetAbsoluteEOF(FSBackingStoreObjID backingStore_t, const FSOffset *eof_i, FSOffset *currentEOF_o)
  825. ;
  826.     IF GENERATINGCFM THEN
  827.         IMPORT_CFM_FUNCTION FSMappedFileSetAbsoluteEOF
  828.     ENDIF
  829.  
  830. ;
  831. ;****************************************************************************
  832. ;    NAVIGATION & ENUMERATION
  833. ;****************************************************************************
  834. ;
  835. ;
  836. ;++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
  837. ;    Object Iteration
  838. ;++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
  839. ;
  840. ;
  841. ;    Function:    FSObjectIterateOnce
  842. ;    Purpose:    Iterate to the next object in the current container and get
  843. ;                aggregate property information.
  844. ;    Inputs:
  845. ;                iterator_t                The object iterator.
  846. ;                objectInfoVersion_i        The version of the FSObjectInformation data record
  847. ;                                        specified by objectInfo_o.
  848. ;    Outputs:
  849. ;                objectInfo_o            Aggregate property information about the current
  850. ;                                        iterator object (optional).
  851. ;                objectRef_o                The object ref of the current iterator object (optional).
  852. ;                objectName_o            The name of the current iterator object (optional).
  853. ;    Notes:
  854. ;                Use kFSInfoCurrentReleasedVersion for infoVersion_i to specify the latest
  855. ;                version of the FSObjectInformation record. infoVersion_i is ignored
  856. ;                if objectInfo_o is omitted.
  857. ;                
  858. ;                objectName_o, if specified, must reference a preinitialized persistent
  859. ;                TextObject of sufficient size to contain the object's name.
  860. ;
  861. ;                If the iterator has reached the end of it's current container, then an
  862. ;                exception will be returned.
  863. ;
  864. ;
  865. ; extern OSStatus FSObjectIterateOnce(FSObjectIteratorObjID iterator_t, FSInfoVersion objectInfoVersion_i, FSObjectInformation *objectInfo_o, FSObjectRef *objectRef_o, FSName objectName_o)
  866. ;
  867.     IF GENERATINGCFM THEN
  868.         IMPORT_CFM_FUNCTION FSObjectIterateOnce
  869.     ENDIF
  870.  
  871. ;
  872. ;    Function:    FSObjectIteratorChangeCurrentScope
  873. ;    Purpose:    Move an object iterator into or out of a container.
  874. ;    Inputs:
  875. ;                iterator_t        The object iterator.
  876. ;                movement_i        The direction to move: into or out of a container.
  877. ;    Outputs:
  878. ;    Notes:
  879. ;                If movement_i is kFSObjectEnter, then the iterator must be positioned on
  880. ;                an object that is capable of containing other objects; it does not need to
  881. ;                actually contain any objects at that time.  That object will become the new
  882. ;                current scope of the iterator and it will be in Start Of Iteration state
  883. ;                (meaning that all objects in the current scope have yet to be returned).
  884. ;                The iterator will not be positioned on any object.
  885. ;                
  886. ;                If movement_i is kFSObjectExit,  then the current scope will become the object
  887. ;                that contains the current scope; the iterator's new position will be the object
  888. ;                that was the current scope.  If the current scope and the outermost scope were
  889. ;                the same, then the outermost scope will also change to the new current scope and
  890. ;                E_ExitIteratorScope is returned (so that you realize you will be iterating outside
  891. ;                of the scope that you used to create the iterator; the iterator remains usable).
  892. ;                
  893. ;                Object iterators keep track of all of the objects between the outermost scope and
  894. ;                the current scope (this is known as the "scope stack").  If any object in the scope
  895. ;                stack is moved, the iterator is invalidated and will return the error
  896. ;                E_IteratorScopeException until it has been explicitly fixed (by FSObjectIteratorRecreate)
  897. ;                or disposed.  This call adds or removes objects from the scope stack.
  898. ;
  899. ;
  900. ; extern OSStatus FSObjectIteratorChangeCurrentScope(FSObjectIteratorObjID iterator_t, FSObjectIteratorMovement movement_i)
  901. ;
  902.     IF GENERATINGCFM THEN
  903.         IMPORT_CFM_FUNCTION FSObjectIteratorChangeCurrentScope
  904.     ENDIF
  905.  
  906. ;
  907. ;    Function:    FSObjectIteratorCreate
  908. ;    Purpose:    Create an iterator for iterating over objects.
  909. ;    Inputs:
  910. ;                outermostScope_t        The initial outermost scope and current scope.
  911. ;                options_i                Controls whether the iterator will traverse objects in
  912. ;                                        a single container or all embedded (nested) containers.
  913. ;                                        Also controls which kinds of objects will be returned.
  914. ;    Outputs:
  915. ;                iterator_o                The object iterator.
  916. ;    Notes:
  917. ;                The outermost scope and current scope of the iterator are set to outermostScope_t.
  918. ;                The iterator is not positioned on any object, though it is inside outermostScope_t.
  919. ;                OutermostScope_t must be an object capable of containing other objects (such as the
  920. ;                Universe, a volume set, a volume, or a folder).  The iterator is put into "Start Of
  921. ;                Iteration" state, meaning that all objects in the current scope have yet to be
  922. ;                returned.
  923. ;                
  924. ;                The File Manager allocates resources and maintains state for every iterator.  When
  925. ;                you have finished using an iterator, you should call FSObjectIteratorDispose to dispose
  926. ;                of it.
  927. ;
  928. ;
  929. ; extern OSStatus FSObjectIteratorCreate(FSObjectRef outermostScope_t, FSObjectIteratorCreationOptions options_i, FSObjectIteratorObjID *iterator_o)
  930. ;
  931.     IF GENERATINGCFM THEN
  932.         IMPORT_CFM_FUNCTION FSObjectIteratorCreate
  933.     ENDIF
  934.  
  935. ;
  936. ;    Function:    FSObjectIteratorDispose
  937. ;    Purpose:    Dispose of an object iterator.
  938. ;    Inputs:
  939. ;                iterator_t        The object iterator.
  940. ;    Outputs:
  941. ;    Notes:
  942. ;                The File Manager will dispose of the iterator and release any resources
  943. ;                allocated to the iterator.  Further attempts to use the iterator will result
  944. ;                in an error.
  945. ;
  946. ;
  947. ;
  948. ;
  949. ; extern OSStatus FSObjectIteratorDispose(FSObjectIteratorObjID iterator_t)
  950. ;
  951.     IF GENERATINGCFM THEN
  952.         IMPORT_CFM_FUNCTION FSObjectIteratorDispose
  953.     ENDIF
  954.  
  955. ;
  956. ;    Function:    FSObjectIteratorRestart
  957. ;    Purpose:    Place an object iterator in the Start Of Iterator state, in its current scope.
  958. ;    Inputs:
  959. ;                iterator_t        The object iterator.
  960. ;    Outputs:
  961. ;    Notes:
  962. ;                The iterator is not positioned on any object.  The iterator is put into "Start Of
  963. ;                Iteration" state, meaning that all objects in the current scope have yet to be
  964. ;                returned.
  965. ;                
  966. ;                You would use this call to completely restart iteration within the current scope,
  967. ;                ignoring any state about objects previously returned in the current scope.  The
  968. ;                outermost scope is not affected.  State information about which objects have been
  969. ;                returned from scopes outside the current scope is unchanged.
  970. ;
  971. ;
  972. ; extern OSStatus FSObjectIteratorRestart(FSObjectIteratorObjID iterator_t)
  973. ;
  974.     IF GENERATINGCFM THEN
  975.         IMPORT_CFM_FUNCTION FSObjectIteratorRestart
  976.     ENDIF
  977.  
  978. ;
  979. ;++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
  980. ;    Object Resolution
  981. ;++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
  982. ;
  983. ;
  984. ;    Function:    FSObjectCreateRef
  985. ;    Purpose:    Get the object ref for a named object in a given container.
  986. ;    Inputs:
  987. ;                container_i                The object container ref.
  988. ;                objectName_i            The name of the target object.
  989. ;    Outputs:
  990. ;                objectRef_o                The resulting object ref.
  991. ;    Notes:
  992. ;
  993. ;
  994. ; extern OSStatus FSObjectCreateRef(FSObjectRef container_i, ConstFSName objectName_i, FSObjectRef *objectRef_o)
  995. ;
  996.     IF GENERATINGCFM THEN
  997.         IMPORT_CFM_FUNCTION FSObjectCreateRef
  998.     ENDIF
  999.  
  1000. ;
  1001. ;    Function:    FSObjectExchange
  1002. ;    Purpose:    Exchange the properties of two objects.  Typically used for "safe
  1003. ;                saving", while maintaining an object's persistent reference.
  1004. ;    Inputs:
  1005. ;                object1_i        One object.
  1006. ;                object2_i        The object to exchange it with.
  1007. ;    Outputs:
  1008. ;    Notes:
  1009. ;                This call is used to allow a "safe save" that preserves an object's
  1010. ;                persistent reference.  For example, you might want to save an updated
  1011. ;                set of properties to an object so that any errors while saving result
  1012. ;                in the object being unchanged; but, you also want the object's persistent
  1013. ;                reference to remain unchanged (so that things like aliases still work).
  1014. ;                
  1015. ;                What you would do is create a second object somewhere (in a temporary
  1016. ;                folder, for example).  Write out all of the properties, both unchanged
  1017. ;                and changed, to the second object.  When done saving, you would call
  1018. ;                FSObjectExchange with both objects; the contents of the two objects get
  1019. ;                swapped in such a way that the original object has the new properties,
  1020. ;                but retains its old persistent reference.
  1021. ;
  1022. ;
  1023. ;
  1024. ;
  1025. ; extern OSStatus FSObjectExchange(FSObjectRef object1_i, FSObjectRef object2_i)
  1026. ;
  1027.     IF GENERATINGCFM THEN
  1028.         IMPORT_CFM_FUNCTION FSObjectExchange
  1029.     ENDIF
  1030.  
  1031. ;
  1032. ;    Function:    FSObjectGetContainerRef
  1033. ;    Purpose:    Get the object ref for the container of a given object.
  1034. ;    Inputs:
  1035. ;                objectRef_i                The object of interest.
  1036. ;    Outputs:
  1037. ;                containerRef_o            The object ref of the container of
  1038. ;                                        containerRef_o.
  1039. ;    Notes:
  1040. ;
  1041. ;
  1042. ; extern OSStatus FSObjectGetContainerRef(FSObjectRef objectRef_i, FSObjectRef *containerRef_o)
  1043. ;
  1044.     IF GENERATINGCFM THEN
  1045.         IMPORT_CFM_FUNCTION FSObjectGetContainerRef
  1046.     ENDIF
  1047.  
  1048. ;
  1049. ;    Function:    FSObjectRefGetFSSpec
  1050. ;    Purpose:    Return an FSSpec for an object (suitable for use with the Files API).
  1051. ;    Inputs:
  1052. ;                object_t            The object.
  1053. ;    Outputs:
  1054. ;                fSSpec_o            An FSSpec that specifies the same object as object_t,
  1055. ;                                    suitable for use with the Files API.
  1056. ;    Notes:
  1057. ;                This call is intended to be used by code that is required to use both the
  1058. ;                Files API and the FileManager API (or has clients that use both APIs).
  1059. ;                For example, a piece of code may already exist with an API that uses FSSpecs,
  1060. ;                but has been converted internally to use the FSObjectRefs; it would use this
  1061. ;                call to produce an FSSpec as an output for the pre-existing API.
  1062. ;                
  1063. ;                It would be best to provide an API that allows its clients to use FSObjectRefs.
  1064. ;
  1065. ;
  1066. ; extern OSStatus FSObjectRefGetFSSpec(FSObjectRef object_t, FSSpec *fSSpec_o)
  1067. ;
  1068.     IF GENERATINGCFM THEN
  1069.         IMPORT_CFM_FUNCTION FSObjectRefGetFSSpec
  1070.     ENDIF
  1071.  
  1072. ; 
  1073. ;
  1074. ; extern OSStatus FSPathnameResolve(FSObjectRef container_i, const char *path_i, ByteCount pathLength_i, FSPathnameType pathType_i, FSObjectRef *objectRef_o)
  1075. ;
  1076.     IF GENERATINGCFM THEN
  1077.         IMPORT_CFM_FUNCTION FSPathnameResolve
  1078.     ENDIF
  1079.  
  1080. ;
  1081. ;    Function:    FSSpecGetFSObjectRef
  1082. ;    Purpose:    Return an FSObjectRef for an object specified via an FSSpec.
  1083. ;    Inputs:
  1084. ;                theFSSpec_t            An FSSpec for the object.
  1085. ;    Outputs:
  1086. ;                theObject_o            An FSObjectRef for the object.
  1087. ;    Notes:
  1088. ;                This call is intended to be used by code that is required to use both the
  1089. ;                Files API and the FileManager API (or has clients that use both APIs).
  1090. ;                For example, a piece of code may already exist with an API that uses FSSpecs,
  1091. ;                but has been converted internally to use the FSObjectRefs; it would use this
  1092. ;                call to take an input FSSpec and convert it to an FSObjectRef to use internally;
  1093. ;                the FSObjectRef would then be disposed before completing the call.
  1094. ;                
  1095. ;                It would be best to provide an API that allows its clients to use FSObjectRefs.
  1096. ;
  1097. ;
  1098. ; extern OSStatus FSSpecGetFSObjectRef(const FSSpec *theFSSpec_t, FSObjectRef *theObject_o)
  1099. ;
  1100.     IF GENERATINGCFM THEN
  1101.         IMPORT_CFM_FUNCTION FSSpecGetFSObjectRef
  1102.     ENDIF
  1103.  
  1104. ;
  1105. ;    Function:    FSVolumeGetInformation
  1106. ;    Purpose:    Get the volume object ref for a given volume object ID.
  1107. ;    Inputs:
  1108. ;                volume_t        The volume's object ID.
  1109. ;    Outputs:
  1110. ;                object_o        The volume's object ref.
  1111. ;    Notes:
  1112. ;
  1113. ;
  1114. ; extern OSStatus FSVolumeGetInformation(FSVolumeObjID volume_t, FSObjectRef *object_o)
  1115. ;
  1116.     IF GENERATINGCFM THEN
  1117.         IMPORT_CFM_FUNCTION FSVolumeGetInformation
  1118.     ENDIF
  1119.  
  1120. ;
  1121. ; extern OSStatus FSObjectGetOnePropertySize(FSObjectRef objectRef_t, const FSProperty *property_i, FSSize *propertySize_o)
  1122. ;
  1123.     IF GENERATINGCFM THEN
  1124.         IMPORT_CFM_FUNCTION FSObjectGetOnePropertySize
  1125.     ENDIF
  1126.  
  1127.     ENDIF
  1128.     ENDIF
  1129.     ENDIF ; __FILEMANAGER__ 
  1130.  
  1131.